docs(openspec): flag-level bash permissions proposal - #16

Summary

OpenSpec change proposal for flag-level-permissions — adds granular, flag-aware command permission control. No implementation yet; this PR is the reviewed proposal (proposal → design → spec → tasks). Implementation follows via /opsx-apply.

Why

permission.bash globs match the whole command string, so flag-level intent can't be expressed reliably: "curl *": "ask" always catches curl -X GET https://api.com even if a narrower allow rule exists. Dangerous flags (find ... -delete, git push --force) deserve their own actions.

Proposed config

{
  "permission": {
    "bash": { "*": "ask", "git *": "allow" },
    "bash_args": [
      { "pattern": "curl -X GET *", "action": "allow" },
      { "pattern": "curl *", "action": "ask" },
      { "pattern": "find * -delete", "action": "ask" },
      { "pattern": "git push --force *", "action": "deny" }
    ]
  }
}

Key design decisions

1. Token-based matching, anchored at command name — * matches zero+ whitespace tokens (find * -delete matches find /tmp -name "*.log" -delete, not plain find /tmp)
2. First-match-wins in declaration order — specific rules before broad ones; avoids the dead-config trap of most-restrictive-wins
3. Args rules take precedence over glob rules — falls back to existing permission.bash glob matching when no args rule matches
4. Force-allow mechanism — flag allow overrides a native opencode ask via permission.ask (status = "allow"), without this the curl -X GET * → allow use case wouldn't work end-to-end
5. Zero behavior change when permission.bash_args is absent

Artifacts

• openspec/changes/flag-level-permissions/proposal.md — what & why
• openspec/changes/flag-level-permissions/design.md — 7 decisions + risks
• openspec/changes/flag-level-permissions/specs/args-permission-matching/spec.md — 5 requirements, 24 scenarios
• openspec/changes/flag-level-permissions/tasks.md — 6 sections, 30 tasks

Next steps

• Review proposal
• Run /opsx-apply to implement (tasks 1–6)

Ultraworked with Sisyphus